home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / pascal / extshr12.zip / EXTRASCR.DOC < prev    next >
Text File  |  1993-07-12  |  34KB  |  714 lines
  1. ╔════════════════════════════════════════════════════════════════════════════╗
  2. ║                  EXTRASCR.TPx v1.20 - DOCUMENTATION FILE                   ║
  3. ║                           release may. 11. 1993                            ║
  4. ╚════════════════════════════════════════════════════════════════════════════╝
  5.  
  6.                               (C) Copyright 1993 Rier Andreas, Moar Christoph
  7.  ────────────────────────────────────────────────────────────────────────────
  8.  
  9.  I. INTRODUCTION
  10.  
  11.     This Turbo Pascal unit (6.0 / 7.0 / 7.0 protected mode) allows you to
  12.     easily write Turbo Vision (R) programs with support for all enhanced
  13.     text modes of graphic cards.
  14.  
  15.     { TURBO C++ LIBRARIES? SEE (V) - REGISTRATION NOTES! }
  16.  
  17.     Why using enhanced text modes?
  18.  
  19.     Well, dialog-oriented programs written with Turbo Vision allow you
  20.     to show the user an awful amount of windows, dialogs, lists and
  21.     other objects on the screen.
  22.     That's a neat thing, but the only problem is that you will sometimes
  23.     have problems finding a free place on the screen.
  24.     Wouldn't it be nice to have more than just a standard 80x25 or
  25.     80x43 resolution in every application?
  26.  
  27.     Nowadays every cheap-o graphic card does support special text modes,
  28.     say it 132x43, 100x60 or anything else. They really do look neat with
  29.     the sample programs that come with your graphic card, but they do
  30.     not usually work with third-party-programs.
  31.     That's because you can bet that the programmer that wrote the
  32.     application you would like to use did include drivers for lots of
  33.     graphic cards, but she/he sure did not include one that would work with
  34.     your vga card.
  35.     We found that out ourselves, that's why we decided to write a package
  36.     that would make it easy for both programmers and end users to write
  37.     and use applications which virtually support every graphic card ever
  38.     built on this planet.
  39.     The concept was really simple: the programmer writing the application
  40.     shouldn't have to worry about different graphic cards, neither should
  41.     she/he have to learn new programming technics, nor should she/he have
  42.     to change a lot just to have the video support included in already
  43.     finished programs.
  44.     On the other side, every end user should have the opportunity to
  45.     easily make the application work with her/his specific graphic card.
  46.  
  47.     That's the idea behind our EXTRASCR.TPx Turbo Pascal (R) Unit.
  48.     Whenever you write a Turbo Vision program, you just include our
  49.     unit and derive your application from TSCRAPPLICATION instead of
  50.     TAPPLICATION. That's it. You don't have to worry about anything else.
  51.     From now on your application will support every graphic card the
  52.     end user possesses.
  53.     On the other side, if you are an end user, you will just need a quick
  54.     glance at the manual that came with your graphic card to tell the
  55.     application how to support YOUR favourite text mode.
  56.     Your xyz card supports a strange thing like 97x41 text mode?
  57.     No problem! The application you just got will easily support it, too!
  58.     You don't have the original user's manual of your graphic card?
  59.     No problem! You start another little tool of our package and you
  60.     will easily find out what text modes your card (and your monitor)
  61.     support.
  62.  
  63.  Page 2                                     EXTRASCR.TPx ver. 1.20 - May 1993
  64.  ────────────────────────────────────────────────────────────────────────────
  65.  
  66.     That all sounds pretty simple. Well, actually it even would be that
  67.     simple, IF ... well if it wouldn't be for the original Turbo Vision
  68.     Application code...
  69.     It wasn't that hard to change Turbo Vision so that we could have
  70.     different screen modes, but different Mouse Drivers, even if they
  71.     are so-called Microsoft compatible, just didn't seem to like the
  72.     new enhanced screen environment. For example, the Microsoft (R) mouse
  73.     driver, the one that comes with MS-DOS or MS-WINDOWS, assumes that
  74.     any video mode except the standard 80x25/80x43 one is a graphic
  75.     video mode! This messes up the screen, since the driver tries to
  76.     map a graphic mouse cursor to a text mode screen.
  77.     The only way to avoid such problems was to write a whole new Mouse
  78.     Event Handler to use in our own programs, disabling the one that
  79.     comes with Turbo Vision...
  80.     And then there was the protected mode version, where we had to find
  81.     out that some interrupts do not work any more, and that some
  82.     Protected Mode Interfaces do not work as they should...
  83.  
  84.     Even writing a whole new assembler event handler wouldn't have been
  85.     that hard, but the stupid thing was that the whole application
  86.     shouldn't notice anything about the changes.
  87.     Neither Turbo Vision nor the programmer should know that something
  88.     changed. The whole thing would have to be completely transparent
  89.     to the outer world.
  90.     Well, it was though. But we think we made it. No one will notice
  91.     that something changed way down there in the heart of Turbo Vision,
  92.     but it did. We hope that every graphic card / mouse combination will
  93.     work in enhanced text modes, and we can almost guarantee that if
  94.     the mouse, well actually the mouse driver, really is Microsoft/
  95.     Logitech/Mouse Systems compatible, then the whole thing will work.
  96.     If some weird mouse driver should not make it (which we don't
  97.     believe), then the whole thing should work if you use the original
  98.     Microsoft Mouse Driver that comes with MS-DOS or MS-WINDOWS.
  99.                                
  100.     How the whole thing works? Well, briefly, that's the way:
  101.     The application you will write with our unit automatically looks
  102.     for a file called STANDARD.DRV, where it will find the information
  103.     about the specific graphic card the end user has installed. If that
  104.     file exists, it will switch into the mode the user did select,
  105.     if not the whole thing will continue with the standard Turbo Vision
  106.     automatic video mode detect. In fact, if the file does not exist, or
  107.     the user will select standard Turbo Vision mode, then our unit kind
  108.     of deactivates itself and the whole thing will be default Turbo Vision.
  109.  
  110.     As a programmer you don't have to worry about different screen sizes.
  111.     Just let Turbo Vision do it for you. A centerd dialog will always be
  112.     centered, say you are in 80x25 mode or in 132x60. Even switching
  113.     between video modes while running the application is completely
  114.     transparent for the program code. A TWindow will actually
  115.     resize (!) itself. If the windows was, say, aligned to the right
  116.     border and filled up about 2/3 of the screen, and you switch to
  117.     higher resolution, the same window will increase in size to mantain
  118.     the same aspect ratio respect to the whole screen size.
  119.  
  120.  Page 3                                     EXTRASCR.TPx ver. 1.20 - May 1993
  121.  ────────────────────────────────────────────────────────────────────────────
  122.  
  123.     With our tools, MAKEDRV.EXE and TESTMODE.EXE (Public Domain, you can
  124.     freely distribute these with the application you wrote with
  125.     EXTRASCR.TPx) it is made totally simple to create a new driver for
  126.     every known and unknown graphic card. As a programmer, you can
  127.     distribute your application with pre-defined graphic card drivers
  128.     (each of the size of a couple hundred bytes), or let the end user use
  129.     MAKEDRV.EXE to create a driver for her/his graphic card.
  130.     An empty screen driver (BUILTIN.DRV, for example) is needed so that
  131.     the user can still select between 80x25 and 80x43/50 video modes.
  132.     If no STANDARD.DRV is found, then our unit completely deactivates
  133.     itself. No video mode selection box is built upon call.
  134.     We furnish an empty driver file (BUILTIN.DRV) which can be copied to
  135.     the name of STANDARD.DRV. The same effect can be generated by starting
  136.     MAKEDRV.EXE and creating a new driver file with no special modes, just
  137.     title line and version character (as of now, still 'a').
  138.  
  139.  
  140.  ────────────────────────────────────────────────────────────────────────────
  141.  
  142. II. COPYRIGHT NOTES
  143.  
  144.     EXTRASCR.TPx (C) is copyrighted 1993 by
  145.  
  146.     Rier Andreas                                   Moar Christoph
  147.        c/o KWK                                        c/o KWK
  148.        Kaulbachstr. 29/a                              Kaulbachstr. 29/a
  149.        8000 Munich 22                                 8000 Munich 22
  150.        Germany                                        Germany
  151.  
  152.        ...or...                                       ...or...
  153.  
  154.        Plojerweg 12                                   Langrain 21
  155.        39040 Kastelruth                               39043 Chiusa
  156.        Italy                                          Italy
  157.  
  158.  
  159.     EMAIL TO
  160.  
  161.     rier@lan.informatik.tu-muenchen.de
  162.     moar@lan.informatik.tu-muenchen.de
  163.     (technical university of Munich, Germany)
  164.  
  165.     We gladly accept bug reports and try, if possible, to answer all
  166.     questions regarding our product.
  167.  
  168.  ────────────────────────────────────────────────────────────────────────────
  169.  
  170.  Page 4                                     EXTRASCR.TPx ver. 1.20 - May 1993
  171.  ────────────────────────────────────────────────────────────────────────────
  172.  
  173. III. DISTRIBUTION POLICY
  174.  
  175.     (A) SHAREWARE VERSION
  176.  
  177.     If you are looking at the Shareware version, please feel free to
  178.     use the unit and share it with your friends, as you please.
  179.     You are allowed to copy this package as long as it remains in its
  180.     original distribution package, an archive file with all of
  181.     the following parts (documentation and sample program):
  182.  
  183.       EXTRASCR.TPU (Turbo Pascal 7.0 real mode shareware unit)
  184.       EXTRASC6.TPU (Turbo Pascal 6.0 real mode shareware unit)
  185.                    {if you use TP 6.0, rename EXTRASC6.TPU to EXTRASCR.TPU}
  186.       EXTRASCR.DOC (This documentation file)
  187.       ORDER.TXT    (Order form)
  188.       EXM.PAS      (source code example program)
  189.       EXM.EXE      (compiled sample program)
  190.       MAKEDRV.EXE  (MakeDriver - driver generation tool)
  191.       TESTMODE.EXE (TestMode - find out screen modes tool)
  192.       *.DRV        (some sample drivers)
  193.  
  194.     (B) REGISTERED VERSION
  195.  
  196.     If you own the registered version, which you can get by mailing
  197.     $20 or 30DM to the above address, you are free to use it in programs
  198.     showing your copyright, and you can freely distribute the MAKEDRV
  199.     tools together with your application, so that the end user will be
  200.     able to create his graphic driver. You CANNOT distribute the
  201.     registered Turbo Pascal Unit if not as a part of a compiled program.
  202.     Registered version archive contents:
  203.  
  204.       EXTRASCR.TPP (Turbo Pascal 7.0 protected mode unit)
  205.       EXTRASCR.TPU (Turbo Pascal 7.0 real mode unit)
  206.       EXTRASC6.TPU (Turbo Pascal 6.0 real mode unit)
  207.                    {if you use TP 6.0, rename EXTRASC6.TPU to EXTRASCR.TPU}
  208.       EXTRASCR.DOC (This documentation file)
  209.       EXM.PAS      (source code example program)
  210.       EXM.EXE      (compiled sample program)
  211.       MAKEDRV.EXE  (MakeDriver - driver generation tool)
  212.       TESTMODE.EXE (TestMode - find out screen modes tool)
  213.       *.DRV        (some sample drivers)
  214.  
  215.       If you are working in both REAL / PROTECTED mode of TP 7.0, then
  216.       ABSOLUTELY READ part (VIII) of this documentation to know
  217.       about the specifications of the protected mode unit.
  218.  
  219.  ────────────────────────────────────────────────────────────────────────────
  220.  
  221.  Page 5                                     EXTRASCR.TPx ver. 1.20 - May 1993
  222.  ────────────────────────────────────────────────────────────────────────────
  223.  
  224. IV. PRODUCT WARRANTY
  225.  
  226.     WE DO NOT WARRANT THAT THE SOFTWARE IS ERROR FREE.
  227.     WE DISCLAIM ALL WARRANTIES WITH RESPECT TO THE SOFTWARE, EITHER
  228.     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES
  229.     OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  230.     NONINFRINGEMENT OF THIRD PARTY RIGHTS.
  231.  
  232.     NO LIABILITY FOR CONSEQUENTIAL DAMAGES.  IN NO EVENT SHALL
  233.     WE BE LIABLE FOR CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES OF
  234.     ANY KIND ARISING OUT OF THE DELIVERY, PERFORMANCE OR USE OF THE SOFTWARE,
  235.     EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  236.     IN NO EVENT WILL WE BE LIABLE FOR ANY CLAIM, WHETHER IN CONTRACT, TORT
  237.     OR ANY OTHER THEORY OF LIABILITY, EXCEED THE LICENSE FEE PAID BY
  238.     THE REGISTERED USER.
  239.  
  240.  ────────────────────────────────────────────────────────────────────────────
  241.  
  242. V.  REGISTRATION NOTES
  243.  
  244.     Get registered!
  245.  
  246.     By mailing 20$ or 30DM along with your address and your choice
  247.     of diskette type (or, if you wish, your EMAIL account) you will
  248.     get the newest release of the software, along with information,
  249.     discounts on future upgrades and free major bug fixes, as far as
  250.     possible.
  251.  
  252.     Use the ORDER.TXT order form for product order/information.
  253.     Deliver times may delay when your orders reach us in march, april,
  254.     august or september. In such cases, you might prefer to write
  255.     to our address in Italy.
  256.  
  257.     You are also encouraged to report any improvement or idea concerning
  258.     the EXTRASCR package. This will help to release improved future
  259.     versions, and you will actively participate in the evolution process
  260.     of the unit.
  261.  
  262.     !!! C++ VERSION !!!
  263.  
  264.     Are you programming with Turbo C++ and you would like to use this
  265.     unit in C programs? Let us know about it, there might be a C++
  266.     version of this unit soon!
  267.  
  268.  ────────────────────────────────────────────────────────────────────────────
  269.  
  270.  Page 6                                     EXTRASCR.TPx ver. 1.20 - May 1993
  271.  ────────────────────────────────────────────────────────────────────────────
  272.  
  273. VI. UNIT INTERFACE
  274.  
  275.     The following objects, functions and/or type definitions are defined
  276.     in our EXTRASCR.TPx unit.
  277.  
  278.     const
  279.       CfgNoError            = 0;
  280.       CfgFileNotFound       = 1;
  281.       CfgFileError          = 2;
  282.       CfgWrongVersion       = 3;
  283.  
  284.     type
  285.       drivertype = record
  286.         mode:             byte;
  287.         x_video,y_video:  integer;
  288.         name:             string[27];
  289.       end;
  290.  
  291.       cfFile=file of drivertype;
  292.  
  293.       TScrApplication=object(TApplication)
  294.         cfgError:         integer;
  295.         cfgName:          string;
  296.         cfgFile:          file of drivertype;
  297.         constructor Init;
  298.         function OpenCfgFile: integer;
  299.         procedure SetScreenMode (mode:word); virtual;
  300.         function SetDefaultScreenMode (mode:integer): integer;
  301.         function GetScreenError: integer;
  302.         procedure SelectAMode;
  303.         destructor done; virtual;
  304.         procedure HandleScreenError; virtual;
  305.         procedure SetScrHelpContext (listCont, InfoCont:word);
  306.         function  GetCurrentMode:integer;
  307.         procedure MouseReset;
  308.       end;
  309.  
  310.       PModeSelection=^TModeSelection;
  311.       TModeSelection=object(TListViewer)
  312.         cfgFile:file of DriverType;
  313.         procedure getData(var Rec); virtual;
  314.         procedure SetData(var Rec); virtual;
  315.         function  Datasize:word; virtual;
  316.         constructor Init(var Bounds: TRect; ANumCols: Integer;
  317.           AHScrollBar, AVScrollBar: PScrollBar;AFile: string);
  318.         destructor done; virtual;
  319.         function GetText(Item:integer; MaxLen:integer):string; virtual;
  320.       end;
  321.  
  322.       procedure HideMouse;
  323.       procedure ShowMouse;
  324.  
  325.  
  326.  ────────────────────────────────────────────────────────────────────────────
  327.  
  328.  Page 7                                     EXTRASCR.TPx ver. 1.20 - May 1993
  329.  ────────────────────────────────────────────────────────────────────────────
  330.  
  331. VII. DESCRIPTION
  332.  
  333.     To use the tools provided by EXTRASCR.TPx do the following steps:
  334.     { for protected-mode programs also read part (VIII) }
  335.  
  336.     (1) Use EXTRASCR.TPx in your source {*.TPU or *.TPP}.
  337.     (2) Derive your application from TSCRAPPLICATION instead of TAPPLICATION.
  338.     (3) If you want, include the method SelectAMode in your menubar,
  339.         say, for example, in a 'preferences' menu.
  340.     (4) If you want, use SETSCRHELPCONTEXT if you'd like our pre-defined
  341.         video mode dialog to change the desired HELPCTX value.
  342.     (5) Use MAKEDRV.EXE to generate the driver for your graphic card.
  343.     (6) Put the driver for your graphic card in the same directory where
  344.         the application is located and name it 'standard.drv'. Don't worry
  345.         if you start the application in a batch-job or if the application
  346.         is in your system path, our unit alway looks for the 'standard.drv'
  347.         driver in the same directory as the main program.
  348.         If the unit does not find 'standard.drv', then the init procedure
  349.         continues with default Turbo Vision automatic video mode selection.
  350.         We recommend leaving at least an empty STANDARD.DRV file for the
  351.         user. If an empty file is found, then the user will still be able
  352.         to select between 80x25 and 80x43/50 mode.
  353.         Without any STANDARD.DRV, no video mode selection box is built
  354.         upon call.
  355.  
  356.     (!) This unit, like the original DRIVERS.TPx, CANNOT BE OVERLAID!
  357.         Likewise, it must be put in a fixed, permanent segment and
  358.         CANNOT be moved around in memory. Why this? Well, since
  359.         a new mouse event handler is installed in this unit, it
  360.         has always to be present in memory. Since the overhead produced
  361.         by this unit is just a few thousand bytes (we counted something
  362.         like 3800 bytes!!!), we don't think this should really be a problem.
  363.         The protected mode version of the unit was compiled with the
  364.         options:
  365.                   FIXED PRELOAD PERMANENT.
  366.  
  367.         (actually the same effect as no overlay...)
  368.  
  369.  
  370.     For more details about the unit, look at the sample program
  371.     'exm.pas' or at the following specifications.
  372.  
  373.     The following isn't a complete unit description, it's just a brief
  374.     look at the most important things you might want, but that you don't
  375.     have to know. In fact, the purpose of our unit was to provide a
  376.     transparent, easy-to-use unit to support enhanced screen modes. We
  377.     think that is done by simply following the above 6 points.
  378.     If you really would like to trick around, you have the possibility
  379.     to work around the heart of EXTRASCR. We do not recommend it.
  380.  
  381.  Page 8                                     EXTRASCR.TPx ver. 1.20 - May 1993
  382.  ────────────────────────────────────────────────────────────────────────────
  383.  
  384.     (A) THE RECORD 'DRIVERTYPE'
  385.         mode:      containes the mode number for each enhanced
  386.                    text mode entered with MAKEDRV.EXE.
  387.         x_video:   containes the number of rows of the mode.
  388.         y_video:   containes the number of lines of the mode.
  389.         name:      a string[27] with a brief description of the mode.
  390.  
  391.         TScrApplication.CfgFile is a file of drivertype.
  392.         In the first record of CfgFile the record elements are
  393.         differently occupied:
  394.  
  395.         mode:      containes the driver version. For all releases less or
  396.                    equal to version 1.20, this is always 'a'.
  397.         x_video:   the record number within the CfgFile that will be the
  398.                    default startup mode. If this is set to -1, the default
  399.                    Turbo Vision mode is selected.
  400.         y_video:   not used.
  401.         name:      a string[27] with the name of the driver, say
  402.                    'Speedstar', 'ET4000', 'Trident', 'Oak' ...
  403.  
  404.     (B) CONSTRUCTOR INIT
  405.         Puts the whole path to standard.drv into TScrApplication.CfgName.
  406.         Assigns TScrApplication.CfgName to TScrApplication.CfgFile.
  407.         Sets TScrApplication.CfgError to CfgNoError.
  408.         Selects the Default Mode found in standard.drv.
  409.  
  410.     (C) PROCEDURE SETSCREENMODE
  411.         The core of the whole unit. Be careful NOT to overwrite this
  412.         procedure when deriving from it.
  413.         Switches to Default Mode, resets mouse functionality and does an
  414.         awful lot of more things you don't need to know.
  415.  
  416.         You can use this procedure just as easy as Turbo Vision's own
  417.         SetScreenMode procedure in order to keep compatibility.
  418.  
  419.         If you first set the default video mode to Turbo Vision with
  420.         a call of SETDEFAULTSCREENMODE (-1), then you will be able to
  421.         make calls like
  422.            SETSCREENMODE(smBW80) etc.
  423.  
  424.         If the default video mode is different than -1 (standard 80) or
  425.         -2 (EGA/VGA 80x43) then the parameter is simply ignored and
  426.         our routine switches to the default enhanced video mode.
  427.  
  428.  
  429.     (D) FUNCTION OPENCFGFILE
  430.         Opens the CfgFile. Returns one of the CfgConstants as a error code.
  431.         You might want to read this, but it's more efficient to use
  432.         the HANDLESCREENERROR procedure later described.
  433.  
  434.     (E) FUNCTION SETDEFAULTSCREENMODE
  435.         The parameter 'mode' indicates the record number containing the
  436.         video mode that will be marked as default. See (A). Calling this
  437.         function with argument '-1' would select the Turbo Vision default
  438.         mode.
  439.         Returns one of the CfgConstants as an error code.
  440.  
  441.  Page 9                                     EXTRASCR.TPx ver. 1.20 - May 1993
  442.  ────────────────────────────────────────────────────────────────────────────
  443.  
  444.     (F) FUNCTION GETSCREENERROR
  445.         Returns the last error code and sets CfgError to CfgNoError.
  446.         You can use this whereever you want in your application to
  447.         find out whether some error occurred while installing the
  448.         enhanced screen modes.
  449.         Don't use this in HANDLESCREENERROR (I).
  450.  
  451.     (G) PROCEDURE SELECTAMODE
  452.         Calling this procedure will start a pre-defined dialog allowing
  453.         the user to select a new video mode. If the file standard.drv
  454.         does not exist, the procedure simply returns.
  455.         The selected mode will be marked as DefaultMode.
  456.         Using SETSCRHELPCONTEXT (K) you can tell the dialog which
  457.         HELPCTX value it should set.
  458.  
  459.     (H) DESTRUCTOR DONE
  460.         ... the usual.
  461.         Switches back to the video mode that was set when the application
  462.         was started.
  463.  
  464.     (I) PROCEDURE HANDLESCREENERROR
  465.         This is a abstract method that is called whenever a Cfg Error
  466.         happens. You can overwrite it for handling the different
  467.         errors, but you can also don't care about them. In such a case,
  468.         our unit goes on its way and sets the default Turbo Vision modes
  469.         (e.g. if the driver was not found, or of a wrong version, or
  470.         defective ...). We DO recomend NOT to overwrite this procedure,
  471.         since the whole unit runs perfectly transparent in any error
  472.         event. But if you want to, you can bring up message boxes like
  473.         'Driver not found' and so on. That was done in the sample
  474.         program EXM.PAS, just to show you how to do it. But, once again,
  475.         we think you shouldn't have to care about this procedure.
  476.  
  477.         ATTENTION:
  478.         Don't set the CfgError variable to 0 in this procedure. So don't
  479.         call GetScreenError, for example. If CfgError is set to 0, then
  480.         our screen initialisation cannot correctly continue to set the
  481.         video mode to Turbo Vision and will bring up a runtime error.
  482.  
  483.     (K) PROCEDURE SETSCRHELPCONTEXT
  484.  
  485.         Use this procedure if you would like the pre-defined change
  486.         video mode dialog to set a desired HELPTCTX value.
  487.            ListCont: word    is the HelpCtx for the SelectAMode dialog,
  488.            InfoCont: word    is the HelpCtx for the Info window.
  489.  
  490.     (L) FUNCTION GETCURRENTMODE
  491.  
  492.         You might need this procedure to get the current video mode
  493.         of your application. This is useful when you have to save
  494.         the current mode for various reasons.
  495.         A value of -1 means that standard Turbo Vision mode is active.
  496.         See the DOS shell example for details.
  497.  
  498.     (M) PROCEDURE MOUSERESET
  499.  
  500.         This is useful whenever, for some reasons, the new mouse event
  501.         handler was deactivated. This might happen when you call
  502.         doneevents, for example. See the DOS shell example for details.
  503.  
  504.  Page 10                                    EXTRASCR.TPx ver. 1.20 - May 1993
  505.  ────────────────────────────────────────────────────────────────────────────
  506.  
  507.     (N) DOS SHELL EXAMPLE
  508.  
  509.         In your application, you might have to switch to default text
  510.         mode, for example for calling a DOS shell. This can be easily
  511.         done, you just have to make sure that you will be able to
  512.         reconstruct the video mode that is currently set.
  513.         Take this as an example (Turbo Pascal 6.0 real mode), and keep
  514.         the points marked with (*) in mind. You will have to use them
  515.         whenever you do stuff like this.
  516.         In Borland Pascal 7.0 there is already a DOSSHELL method
  517.         implemented, keep in mind that you will have to derive from it
  518.         and include those six (*) lines.
  519.  
  520.         procedure DosShell;
  521.  
  522.         var
  523.           mode:integer;
  524.         begin
  525. (*)       mode:=GetCurrentMode;
  526. (*)       SetDefaultScreenMode(-1);
  527. (*)       SetScreenMode(0);
  528.  
  529.           {...the following should be known stuff for you}
  530.              DoneSysError;
  531.              DoneEvents;
  532.              DoneVideo;
  533.              DoneMemory;
  534.              SetMemTop(Ptr(BufHeapPtr, 0));
  535.              PrintStr('Type EXIT to return to the program...');
  536.              swapvectors;
  537.              Exec(GetEnv('COMSPEC'), '');
  538.              swapvectors;
  539.              SetMemTop(Ptr(BufHeapEnd, 0));
  540.              InitMemory;
  541.              InitVideo;
  542.              InitEvents;
  543.              InitSysError;
  544.              Redraw;
  545.           {...end known stuff}
  546.  
  547. (*)       MouseReset;
  548. (*)       SetDefaultScreenMode(mode);
  549. (*)       SetScreenMode(0);
  550.         end;
  551.  
  552.  Page 11                                    EXTRASCR.TPx ver. 1.20 - May 1993
  553.  ────────────────────────────────────────────────────────────────────────────
  554.  
  555. VIII. PROTECTED MODE VERSION
  556.  
  557.     Well, as of now, protected mode is a quite dangerous environment
  558.     for programming DOS applications. We had to find that out ourselves.
  559.     Not all DOS/BIOS interrupts are correctly implemented by both Borland's
  560.     DPMI Server or the MICROSOFT WINDOWS (R) DPMI Interface for the DOS Box.
  561.     And, worst thing of all, those two DPMI servers do NOT behave the same
  562.     way...
  563.  
  564.     In fact, the regular EXTRASCR.TPU uses the interrupt 33H,
  565.     function 14H to install the new mouse event handler AND to find out
  566.     the address (segment:offset) of the old, Turbo-Vision event handler.
  567.     Well, believe it or not, this interrupt causes a general protection
  568.     fault error when called in protected mode. Same thing happens if you
  569.     use function 18H or 19H (install alternate event handler, get adress
  570.     event handler) or most of the other int 33H function calls.
  571.     We believe that this interrupt probably tries to write in a code
  572.     segment. Anyway, strange enough, the function 0cH (install
  573.     event handler), the function that actually DOES something (19H
  574.     should just READ a value, for example) and that DOES change some
  575.     memory value, works just fine... :)
  576.     So we had to find out some way to get the address of the Turbo
  577.     Vision Event Handler. We tried all sorts of methods, but there
  578.     doesn't seem to be any possibility to do that completely transparent.
  579.     We found out a way for getting the address, but, strangely enough,
  580.     this would work only when the application was started with Borland's
  581.     DPMI interface. The one implemented by MS WINDOWS would not work.
  582.     
  583.     Version 1.00 had different mouse-status-buffer scanning tecniques,
  584.     and it worked mostly fine, just leaving a "forgotten" mouse cursor
  585.     sometimes on the screen.
  586.     
  587.     Version 1.20 has now complete protected mode support in both Borland
  588.     and Microsoft DPMI environments.
  589.     We recommend using the protected mode version just with computers
  590.     using an 386sx and above chip.
  591.     Our unit uses special 386 assembler commands to solve some interference
  592.     problems (mutually excluding more than one mouse drawing task).
  593.     Using the protected mode version with 286 processors will not cause
  594.     errors, but it will result in a SLOW MOUSE CURSOR REFRESH RATE.
  595.     This is not a bug, but a compromise to avoid task interference with
  596.     processors that do not support interlocked commands as the ones
  597.     provided by 386 processors.
  598.     
  599.     We recommend using the real mode version for such machines.
  600.     
  601.     In fact, what we have right now is NOT a real mode unit ported to
  602.     protected mode, but actually more two completely different unit
  603.     tecniques.
  604.     The way the mouse cursor gets drawn in real mode is completely
  605.     different from the way it gets done in protected mode.
  606.  
  607.  
  608.  Page 12                                    EXTRASCR.TPx ver. 1.20 - May 1993
  609.  ────────────────────────────────────────────────────────────────────────────
  610.  
  611. IX. MAKEDRV DRIVER CREATING TOOL
  612.  
  613.     This program helps you and the end user to generate new drivers for
  614.     every graphic card.
  615.     It is copyrighted 1993 by Rier Andreas, Moar Christoph, but it's
  616.     Public Domain and can be freely distributed, even together with
  617.     an application programmed with EXTRASCR.TPx.
  618.  
  619.     The use of the program is self-explaining, simply remember that,
  620.     when inputting video mode numbers, the program asks for decimal
  621.     values. Watch out! The numbers in your vga manual might be hex numbers.
  622.     The tool 'TESTMODE' always shows video modes in decimal numbers.
  623.     You can create lots of drivers, say 'speedst.drv', 'trident.drv',
  624.     'oak.drv' and so on, but always remember that the driver that should
  625.     be supported by the application has to be called 'standard.drv'.
  626.  
  627.     So, after creating your driver, say 'mycard.drv', put it in the
  628.     same directory as the application you would like to start and
  629.     name it 'standard.drv'.
  630.  
  631.     Use this program to create at least one empty screen driver if
  632.     you want to switch at least between 80x25 and 80x43/50 modes.
  633.     We provide an empty screen driver (BUILTIN.DRV) with our unit,
  634.     too.
  635.  
  636.  ────────────────────────────────────────────────────────────────────────────
  637.  
  638. X. TESTMODE.EXE
  639.  
  640.     Testmode.exe is a little freeware tool (no copyright, no support, no
  641.     warranty whatsoever) that is intended to help users that do not have
  642.     a graphic card manual to find out the screen mode numbers of all
  643.     the enhanced text modes supported by their graphic card (and monitor).
  644.     The program is self-explaining and can be freely distributed with
  645.     any application.
  646.  
  647.  ────────────────────────────────────────────────────────────────────────────
  648.  
  649. XI. KNOWN BUGS
  650.  
  651.     Writing this unit and having it fully compatible wasn't an easy task,
  652.     so we know that this unit will not be bug-free.
  653.     
  654.     Using this unit with 386 machines or above shouldn't produce those
  655.     forgotten mouse cursors as of release 1.00.
  656.     Using 286 or less will - rather rarely - cause a interrupt interference
  657.     that sometimes leaves a mouse cursor on the screen. This happens if
  658.     a mouse interrupt happens in between two assembler commands without
  659.     having a 386 processor.
  660.     Just move a window over it or refresh the screen to get rid of it :).
  661.     Sorry about that...
  662.     And, once again, standard mode still is fully compatible and does not
  663.     provide any errors.
  664.     
  665.     We recommend using the protected mode version just with machines with
  666.     a 386 processor or above. Using it with 286 will cause a slow mouse
  667.     refresh rate. This is not a bug, it's a compromise we had to make
  668.     with machines that do not support memory-read-interlocked commands.
  669.  ────────────────────────────────────────────────────────────────────────────
  670.  
  671.  Page 13                                    EXTRASCR.TPx ver. 1.20 - May 1993
  672.  ────────────────────────────────────────────────────────────────────────────
  673.  
  674. XII. REVISION HISTORY FOR VERSION 1.20
  675.  
  676.  
  677.     Major changes since revision 1.00 are:
  678.     --------------------------------------
  679.     
  680.     (1)  Full protected mode support with 386(sx)-class-machines and above.
  681.          Compatible protected mode support for 286-class-machines, problems
  682.          with 'forgotten' mouse cursors might happen.
  683.          We recommend using protected mode WITH enhanced video modes only
  684.          on 386(sx)-class-machines.
  685.          Protected mode works fine in both Borland's and MS-WINDOWS'
  686.          Dos Protected Mode.
  687.     (2)  EGA/VGA 80x43/50 video mode included in mode selection box.
  688.          Version 1.00 just didn't show up the mode selection box if no
  689.          driver file was found.
  690.          We recommend having an empty driver file (BUILTIN.DRV is provided)
  691.          in order to still be able to select EGA/VGA modes.
  692.     (3)  Solved mutually-exclusive problems.
  693.          Version 1.00 sometimes kind of 'forgot' the mouse cursor on the
  694.          screen while in enhanced screen modes.
  695.          We fully solved this problem with 386(sx)-class-machines and
  696.          above, and we diminished the occurence of those conflicts on
  697.          286 and lower.
  698.     (4)  Got rid of GPF's (general protection faults) in protected mode
  699.          version caused by some interrupt services not provided by
  700.          Borland's or Microsoft's Dos Protected Mode Interface's.
  701.          The way the mouse cursor is drawn in real mode is completely
  702.          different from the one in protected mode.
  703.          The different mouse-status-buffer scanning tecniques used in
  704.          version 1.00 are no longer necessary.
  705.     (5)  Got rid of some minor bugs.
  706.          
  707.     
  708.  
  709.  
  710.  
  711.  
  712.                                  EXTRASCR.TPx release 1.20 documentation file
  713.                                                     06.07.1993  1:30 P.M. CET
  714.